home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / hdiff122.zip / HDIFF.DOC < prev    next >
Text File  |  1988-01-07  |  25KB  |  594 lines
  1.                                   hdiff 1.22
  2.  
  3.         Purpose
  4.         -------
  5.         Hdiff compares two DOS text files and records the differences
  6.         between them in a third file.  Although hdiff can be used for
  7.         simple "what's changed?" purposes, its real function is to
  8.         assist in maintaining program source code or similar text files
  9.         that change over time.  By maintaining a original, base file and
  10.         a series of "difference" files, it's possible to retain all
  11.         versions of a file at a great savings in space over retaining
  12.         the full text of all versions.
  13.  
  14.         The hdiff system includes an auxiliary program, hed, that is
  15.         used to apply the difference files to the original (although
  16.         EDLIN can also be used if the files are small enough).
  17.  
  18.  
  19.         New in version 1.22
  20.         -------------------
  21.         The following features have been changed or added since version
  22.         1.14, the last publicly released version:
  23.  
  24.         1. A new difference-applier (HED.EXE) is included.  This
  25.         replaces most use of EDLIN for the hdiff system and allows you
  26.         to apply multiple update files in one operation.
  27.  
  28.         2. The syntax of hdiff has changed slightly:
  29.             a. A third filename can be supplied on the command line.
  30.                This replaces the redirection used in earlier versions.
  31.             b. It is no longer necessary to specify a maximum number
  32.                of lines (the old -nnnn parameter).  For downward
  33.                compatibility, hdiff 1.22 will accept and ignore the
  34.                parameter if present.
  35.  
  36.         3. The true file date of the original file is retained if you
  37.         use hdiff and hed as described below.
  38.  
  39.         4. Maximum line length has been extended to 1000 characters.
  40.  
  41.  
  42.         Running hdiff
  43.         -------------
  44.         The general syntax for hdiff is:
  45.  
  46.             hdiff [-ecs] old-file new-file [dif-file]
  47.  
  48.         The simplest use of hdiff is exemplified by:
  49.  
  50.             hdiff oldfile.txt newfile.txt
  51.  
  52.         which displays a simple report of differences between the two
  53.         files: it shows which lines of OLDFILE.TXT do not appear in
  54.         NEWFILE.TXT (deletions), and which lines of NEWFILE.TXT do not
  55.         appear in OLDFILE.TXT (insertions).  The simple change report
  56.         consists of text lines in this format:
  57.  
  58.             nnnn[+/-] text
  59.  
  60.         A '+' format indicates that the line is new (an insertion); the
  61.         '-' indicates that the line is gone (a deletion).  Thus:
  62.  
  63.             0001- This line appears in the old file only
  64.             0001+ This line appears in the new file only
  65.  
  66.         The 'nnnn' represents the line number.  For '+' lines, it's the
  67.         line number in the new file; for '-' lines, it's the line number
  68.         in the old file.
  69.  
  70.         (Note that the first file named on the command line is always
  71.         assumed to be the "old" file, and the second is the "new" file.)
  72.  
  73.         If you want the report to be sent to a text file rather than to
  74.         the screen, simply include the file name as a third parameter:
  75.  
  76.             hdiff oldfile.txt newfile.txt changes.txt
  77.  
  78.         NOTE: the simple report does not show lines that have been
  79.         moved.  The edlin-format report (-e switch) does include moved
  80.         lines.  Use the -e report for maintaining difference files; the
  81.         simple report does not contain enough information.
  82.  
  83.  
  84.         Optional switches
  85.         -----------------
  86.         Here are the switches that can optionally be added to the
  87.         command line.  They must precede the file names:
  88.  
  89.         -c      Case insensitive: hdiff ignores differences in
  90.                 alphabetic case.  Thus, the two lines:
  91.  
  92.                         This is text
  93.                         THIS IS TEXT
  94.  
  95.                 are not reported as changed.
  96.  
  97.         -e      Edlin: produce an edlin-compatible difference file
  98.                 rather than the simple difference report described
  99.                 above.  This switch is also used to created hed-format
  100.                 files.  See succeeding sections for more information.
  101.  
  102.         -s      Space insensitive: hdiff ignores differences in spacing.
  103.                 This, the two lines:
  104.  
  105.                         This is text
  106.                         This  is    text
  107.  
  108.                 are not reported as changed.
  109.  
  110.         The switches may be combined, and they may be in any order:
  111.  
  112.                 -e -c
  113.                 -ec
  114.                 -ce
  115.                 -c -e
  116.  
  117.         are all equivalent.  All switches must, however, precede the
  118.         first filename.
  119.  
  120.         Examples of hdiff use:
  121.  
  122.             hdiff foo.c newfoo.c
  123.  
  124.                 compares file 'foo.c' with file 'newfoo.c' and displays
  125.                 a simple report showing insertions (lines in newfoo that
  126.                 do not appear in foo) and deletions (lines in foo that
  127.                 do not appear in newfoo).  Lines that have been moved
  128.                 but are otherwise unchanged do not appear in this
  129.                 report.
  130.  
  131.             hdiff -ec foo.c newfoo.c foo.114
  132.  
  133.                 compares foo.c with newfoo.c, ignoring case differences,
  134.                 and prepares an edlin/hed script in the file foo.114.
  135.                 This script, if applied to foo as described below, will
  136.                 create a copy of newfoo.
  137.  
  138.  
  139.         Applying difference files: edlin and version control
  140.         ----------------------------------------------------------
  141.         The main purpose of hdiff is to assist you in maintaining
  142.         multiple versions of program source or other text files.  Many
  143.         programmers like to keep archival copies of old source, for any
  144.         of a number of reasons (one reason: sometimes changes don't work
  145.         and it's necessary to go back to a previous version!).  You
  146.         could simply keep an archive or library with the complete text
  147.         of all versions, but this is wasteful of disk space.
  148.  
  149.         A better solution (short of purchasing a true SCCS ["Source Code
  150.         Control System"] for big bucks) is to use hdiff and hed or edlin
  151.         to keep one original source file plus smaller difference files
  152.         that can be used to re-create any version.
  153.  
  154.         To see how this works, assume that you have an old version of
  155.         your program MYPROG.C (in a file called MYPROG.SCC) and a new
  156.         version named MYPROG.C:
  157.  
  158.                 myprog.scc     (version 1.00)
  159.                 myprog.c       (version 1.10)
  160.  
  161.         To create a difference file, use hdiff:
  162.  
  163.             hdiff -e myprog.scc myprog.c myprog.110
  164.  
  165.         After hdiff is finished, you will have a file (MYPROG.110) that
  166.         contains the differences between 1.00 and 1.10.  Because of the
  167.         -e switch, this file is in a special format:  it is actually the
  168.         text of a series of edlin commands that would turn version 1.00
  169.         source into version 1.10 source.  It is an edlin script.  So, if
  170.         you were to execute the commands (remember that MYPROG.SCC is
  171.         version 1.00):
  172.  
  173.             copy myprog.scc myprog.c
  174.             edlin myprog.c < myprog.110
  175.  
  176.         the result (after edlin finished) would be a file called
  177.         MYPROG.C that contains the source for version 1.10.  Thus,
  178.         between the original (1.00) MYPROG.SCC and the difference file
  179.         MYPROG.110 you have all you need to re-create either version of
  180.         the program.  Chances are, however, that MYPROG.110 is much
  181.         smaller than the full source for MYPROG.C, so considerable
  182.         storage is saved.
  183.  
  184.         Note that edlin cannot deal, in this context, with files larger
  185.         than about 48K.  If you try to apply a difference file to a base
  186.         file larger than 48K using edlin, the resultant file will be
  187.         damaged and probably unusable.  For this reason and others, we
  188.         recommend using the supplied program "hed" rather than edlin.
  189.  
  190.  
  191.         Using hed
  192.         ---------
  193.         Hed is a simple progr